<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Stefan Baebler">
   <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]">
   <title>Makumba application example</title>
   <link rel="stylesheet" type="text/css" media="all" href="main.css">
   <script type="text/javascript" src="main.js"></script>
</head>
<body>
<script type="text/javascript">
   makeNavBar("");
</script>

<h1><a NAME="Example">&nbsp;</a>Makumba application example</h1>

This is an example for a very simple web application to illustrate the
basic princpiles of building web applications with Makumba JSP tag library.
<p>
In this example we will build a web application for managing data about our business partners in following steps:
<ol>
<li><a href="#mdd">Defining data structure - MDD</a></li>
<li><a href="#jsp">Wrinting JSP pages</a>
	<ul>
	<li><a href="#list">Listing objects</a></li>
	<li><a href="#object">Showing single object</a></li>
	<li><a href="#new">Creating new object</a></li>
	<li><a href="#edit">Editing existing object</a></li>
	<li><a href="#layout">Fine tuning page layout</a></li>
	</ul>
</li>
<li><a href="#BL">Business Logic</a></li>
</ol>

<h2><a name="mdd">&nbsp;</a>MDD - Makumba Data Definition</h2>

For explanations please refer to <a href="makumba-spec.html#Data_Description">Data
Definition</a> section of the specification.

<p>The Makumba Data Definitions (MDDs) can be placed anywhere in the <i>CLASSPATH</i>, in the <tt>dataDefinitions</tt> folder.</p>

<pre class="example">
<div class="example-header">dataDefinitions/organisation/Partner.mdd</div>
name=not null char[40]       ;Name
city=char[40]                ;City
country= ptr <b>general.Country</b> ;Country
phone=char[20]               ;Phone
fax=char[40]                 ;Fax
email=char[40]               ;E-Mail
homepage=char[50]            ;Home Page on the Internet
comment=text                 ;Other comments
personalContacts= set <b>general.Person</b> ; precise personal contacts at the partner
</pre>

<pre class="example">
<div class="example-header">dataDefinitions/organisation/Country.mdd</div>
name=char[60]               ;Country
iso2letterCode=fixed char[2];2-letter ISO code
</pre>

<pre class="example">
<div class="example-header">dataDefinitions/organisation/Person.mdd</div>
name=char[60]               ;name
birthdate=date              ;birthdate
</pre>

<h3>Changes in the table in the database</h3>
<p>To be able to change the table in the database you need to add the following 
  line to the database proprieties &lt;server_name&gt;_&lt;database_engine&gt;_&lt;database_name&gt;.properties, e.g. <tt>example/WEB-INF/classes/localhost_mysql_testdatabase.properties</tt></p>

<pre class="example">
alter#MDD_name=true
</pre>
(you should comment it after the changes: #alter#MDD_name=true)</p>
<p>In order to <strong>create the table </strong>or make the MDD changes available, just reload Tomcat (or any engine that implement Java Servlet API).</p>
<h2><a name="jsp">&nbsp;</a>JSP - Java Server Pages</h2>
For explanation please refer to <a href="makumba-spec.html#Presentation">Makumba
JSP tags</a> section of the specification.


<h3><a name="list">&nbsp;</a>Listing objects</h3>
Page <code><b>partnerList.jsp</b></code> will be showing the list of all partners, each entry with:
<ul>
 <li>brief summary (name and city)
 <li>link to a page with more detailed information
</ul>
<pre class="example">
<div class="example-header">example/parnerList.jsp</div>
&lt;%@ taglib uri="<span style="color:#FF0000;">http://www.makumba.org/presentation</span>" prefix="<span style="color:#FF0000;">mak</span>" %>

&lt;h2>Partners:&lt/h2>

&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">list from</span><span style="color:#006600;">="<i>organisation.Partner p</i>"</span>>
   &lt;dt>&lt;a href="partner.jsp?partner=&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span>=<i><span style="color:#006600;">"p"</span></i>/>">
                &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span>="<i>p.name"</i>/>
   &lt;/a>,
   &lt;i>&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">=<i>"p.city"</i></span>/>&lt;/i> &lt;/dt> 
	&lt;dd>&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">list from</span><span style="color:#006600;">="<i>p.personalContacts c</i>" </span><span style="color:#000099;">separator</span>="&lt;br>"</span>>
		&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">=<i>"c.name"</i></span>/> 
	&lt;/<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">list</span>>&lt;/dd>
&lt;/<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">list</span>>

&lt;hr>
[&lt;a href="partnerNew.jsp">New partner entry&lt;/a>]
</pre>

If we are starting with an empty database it will be at first rendered to:<br><br>

<div class="plainstyle">
<h2>Partners:</h2>
<hr>
[<a href="partnerNew.jsp">New partner entry</a>]
</div>

<br>

But once we enter some data it will look more like:<br><br>

<div class="plainstyle">
<h2>Partners:</h2>
<dt><a href="partner.jsp?partner=fg526f8">PlasticWing Airlines</a>, <i>Cambridge</i> </dt>
<dd> John Doe<br> John Smith</dd>
<dt><a href="partner.jsp?partner=fwet4tw">Pasta al'Dente s.p.a</a>, <i>Turin</i>  </dt>
<dd>Benny Andersson<br>Bjorn Ulvaeus</dd>
<dt><a href="partner.jsp?partner=h6e5678">Some Company Ltd.</a>, <i>Somewherewille</i> </dt>
<dd>Robert Wells</dd>
<dt><a href="partner.jsp?partner=456gw45">ACME gadgets</a>, <i>Death Walley</i>  </dt>
<dt><a href="partner.jsp?partner=56gfy67">Protect gamblers</a>, <i>Las Vegas</i>  </dt>
<dd>Frida<br>Agneta<br>Cher</dd>

<hr>
[<a href="partnerNew.jsp">New partner entry</a>]
</div>
<br>
For additional options see the specification of <a href="makumba-spec.html#tab_list">mak:list</a> and
<a href="makumba-spec.html#tab_list">mak:value</a>.


<h3><a name="object">&nbsp;</a>Object details</h3>
Page <code><b>partner.jsp</b></code> will be showing all fields of <code>organisation.Partner</code> objects.

<pre class="example">
<div class="example-header">example/partners.jsp</div>
&lt;%@ taglib uri="<span style="color:#FF0000;">http://www.makumba.org/presentation</span>" prefix="<span style="color:#FF0000;">mak</span>" %>

&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">object from</span><span style="color:#006600;">="<i>organisation.Partner p</i>" </span><span style="color:#000099;">where</span><span style="color:#006600;">=<i>"p=$partner"</i></span>>
    &lt;h2>&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>name</i>"</span>/>&lt;/h2>

    &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>city</i>"</span>/>,
      &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>country<b>.name</b></i>"</span>/>
    Home Page: &lt;b>&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>homepage</i>"</span>/>&lt;/b>
    &lt;p>
    You can send them an email to: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="<i>p.email</i>"</span>/>&lt;br>
    Call me: &lt;b>&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>phone</i>"</span>/>&lt;/b>&lt;br>
    Comment: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="p.<i>comment</i>"</span>/>
    &lt;p>
    &lt;a href="partnerEdit.jsp?partner=&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="<i>p</i>"</span>/>">edit&lt;/a>
&lt;/<span style="color:#FF0000;">mak</span>:object>

&lt;hr>
[&lt;a href="partnerList.jsp">List them all&lt;/a>]
</pre>

Is rendered to:<br><br>

<div class="plainstyle">
<h2>Some company Ltd.</h2>
Somewherewille, Bangladesh
<br>Home Page: <b><a href="http://www.example.com">http://www.example.com</a></b>
<p>You can send them an email to: <a href="mailto:info@example.com">info@example.com</a>
<br>Call me: <b>+1 23 456789</b>
<br>Comment: They are very rich!!!

<p><a href="partnerEdit.jsp?partner=gi1fv6z">edit</a>
<hr>
[<a href="partnerList.jsp">List them all</a>]
</div>
<br>
Note that OQL expression <code>p.country.name</code> was evaluated to "Bangladesh" automagically. Makumba joined the Partner and Country tables when performing the query, and can make even more sophisticated table joins when needed.
<p>
For additional options see the specification of <a href="makumba-spec.html#makobject">mak:object</a> and
<a href="makumba-spec.html#makvalue">mak:value</a>.







<h3><a name="new">&nbsp;</a>New object creation</h3>




Page <code><b>partnerNew.jsp</b></code> will require only the basic info when 
creating a new object: 
<pre class="example">
<div class="example-header">example/partnerNew.jsp</div>
&lt;%@ taglib uri="<span style="color:#FF0000;">http://www.makumba.org/presentation</span>" prefix="<span style="color:#FF0000;">mak</span>" %>

&lt;h2>New partner&lt;/h2>

&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">newForm type</span><span style="color:#006600;">="<i>organisation.Partner</i>" </span><span style="color:#000099;">action</span><span style="color:#006600;">=<i>"partnerList.jsp"</i></span>>
   Name: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input name</span><span style="color:#006600;">="<i>name</i>"</span>/> &lt;br>

   City: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input name</span><span style="color:#006600;">="<i>city</i>"</span>/> &lt;br>
   Country: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input name</span><span style="color:#006600;">="<i>country</i>"</span>/> &lt;a href="countryNew.jsp">Add countries&lt;/a>&lt;br>
   &lt;input type="submit" value="Create">
&lt;/<span style="color:#FF0000;">mak</span>:newForm>

&lt;hr>
[&lt;a href="partnerList.jsp">Back to list&lt;/a>]
</pre>

<div class="plainstyle">
<h2>New partner</h2>
<form action="partnerList.jsp">
   Name: <input name="name"> <br>

   City: <input name="city"> <br>
   Country: <select name="country">
   		<option>Afganisthan</option><option>Bangladesh</option><option>...</option><option>Zimbabwe</option>
   </select> <a href="countryNew.jsp">Add countries</a><br>
   <input type="submit" value="Create" onClick="alert('this is just an example'); return false;">
</form>
<hr>
[<a href="partnerList.jsp">Back to list</a>]
</div>
<br>
The user can decide to omit city and country information as well, but due to the <code>not null</code> attribute of field <code>name</code> in the <a href="#mdd">MDD</a>, Makumba will not create a new object unless some name is specified.<p>





Page <code><b>countryNew.jsp</b></code> looks almost the same as <code><b>partnerNew.jsp</b></code>:

<pre class="example">
<div class="example-header">example/countryNew.jsp</div>
&lt;%@ taglib uri="<span style="color:#FF0000;">http://www.makumba.org/presentation</span>" prefix="<span style="color:#FF0000;">mak</span>" %>

&lt;h2>New country&lt;/h2>

&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">newForm type</span><span style="color:#006600;">="<i>general.Country</i>" </span><span style="color:#000099;">action</span><span style="color:#006600;">=<i>"partnerList.jsp"</i></span>>
   Name: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>name</i>"</span>/> &lt;br>
   ISO code: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>iso2letterCode</i>"</span> size</span><span style="color:#006600;">="<i>5</i>"</span>/>&lt;br>
   &lt;input type="submit" value="Add">
&lt;/<span style="color:#FF0000;">mak</span>:newForm>

&lt;hr>
[&lt;a href="partnerList.jsp">Back to list&lt;/a>]
</pre>

<div class="plainstyle">
<h2>New country</h2>
<form action="partnerList.jsp">
   Name: <input name="name" type="text" value="" maxlength="60" > <br>
   ISO code: <input name="iso2letterCode" type="text" value="" size="5" maxlength="2" > <br>
   <input type="submit" value="Add" onClick="alert('this is just an example'); return false;">
</form>
<hr>
[<a href="partnerList.jsp">Back to list</a>]
</div>





<p>
For additional options see the specification of <a href="makumba-spec.html#tab_forms">mak:newForm</a> and
<a href="makumba-spec.html#tab_forms">mak:input</a>.

<h3><a name="edit">&nbsp;</a>Editing existing objects</h3>
In <code><b>partnerEdit.jsp</b></code> we could edit all (non-fixed) fields, but here we decided to not support editing of some fields (Field <code>name</code> in this case)

<pre class="example">
<div class="example-header">example/partnerEdit.jsp</div>
&lt;%@ taglib uri="<span style="color:#FF0000;">http://www.makumba.org/presentation</span>" prefix="<span style="color:#FF0000;">mak</span>" %>

&lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">object from</span><span style="color:#006600;">="<i>organisation.Partner p</i>" </span><span style="color:#000099;">where</span><span style="color:#006600;">=<i>"p=$partner"</i></span>>
   &lt;h2>Edit &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">value expr</span><span style="color:#006600;">="<i>p.name</i>"</span>/>&lt;/h2>
   &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">editForm object</span><span style="color:#006600;">="<i>p</i>" </span><span style="color:#000099;">action</span><span style="color:#006600;">=<i>"partnerList.jsp"</i></span>>

      City: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>city</i>"</span>/> &lt;br>
      Country: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>country</i>"</span>/>
        &lt;a href="countryNew.jsp">Add countries&lt;/a>&lt;br>
        
      Home Page: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>homepage</i>"</span>/>
      &lt;p>
      Email: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>email</i>"</span>/>&lt;br>
      Phone: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>phone</i>"</span>/>&lt;br>
      Comment: &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">input field</span><span style="color:#006600;">="<i>comment</i>"</span>/>&lt;br>
      &lt;input type="submit" value="Save">
   &lt;/<span style="color:#FF0000;">mak</span>:editForm>

   &lt;<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">deleteLink object</span><span style="color:#006600;">="<i>p</i>" </span><span style="color:#000099;">action</span><span style="color:#006600;">=<i>"partnerList.jsp"</i></span>>Delete this&lt;/<span style="color:#FF0000;">mak</span>:<span style="color:#000099;">deleteLink</span>>

&lt;/<span style="color:#FF0000;">mak</span>:object>

&lt;hr>
[&lt;a href="partnerList.jsp">Back to list&lt;/a>]
</pre>

<div class="plainstyle">
<h2>Edit Some Company Ltd.</h2>
<form action="partnerList.jsp">
   City: <input name="city" value="Somewherewille"> <br>
   Country: <select name="country">
   		<option>Afganisthan</option><option SELECTED>Bangladesh</option><option>...</option><option>Zimbabwe</option>
   </select> <a href="countryNew.jsp">Add countries</a><br>
   Home Page: <input name="homepage" value="http://www.example.com">
   <p>
   Email: <input name="email" value="info@example.com"><br>
   Phone: <input name="phone" value="+1 23 456789"><br>
   Comment: <textarea name="comment" rows="3" cols="20">They are very rich!!!</textarea><br>

   <input type="submit" value="Save" onClick="alert('this is just an example'); return false;">
</form>
<a href="partnerList.jsp" onClick="alert('this is just an example'); return false;">Delete this</a>
<hr>
[<a href="partnerList.jsp">Back to list</a>]
</div>


<p>
For additional options see the specification of <a href="makumba-spec.html#tab_form">mak:editForm</a>,
<a href="makumba-spec.html#tab_form">mak:input</a> and <a href="makumba-spec.html#tab_form">mak:deleteLink</a>.


<h3><a name="layout">&nbsp;</a>Fine-tuning layout</h3>
Always make things work first, then bother with details.

<p>In order to keep your code as clean as possible, we advise you to break it
down into small, human-managable files and include them in your pages with
&lt;jsp:include /> directive, eg:
<pre class="example">
&lt;jsp:include page="header.jsp"/>
</pre>
You can also take some size of the .jsp files and improve their readability by seperating the layout specification into  seperate <a href="http://www.w3.org/Style/CSS/">Cascading Style Sheets</a>.

<h2><a name="BL">&nbsp;</a>BL - Business Logic</h2>


Makumba protects the changes in the database thus to be able to add, edit and remove records you have to
define the respective methods.
<p>
For this example you will need to define the following methods in, for example, Logic.java.
See how makumba <a href="makumba-spec.html#javahand">looks for the handlers</a>.
<P>
<code>public void on_newPartner(Dictionary d, Attributes a, Database db) {}</code><BR>
<code>public void on_editPartner(Pointer p, Dictionary d, Attributes a, Database db) {}</code><BR>
<code>public void on_newCountry(Dictionary d, Attributes a, Database db) {}</code><BR>
<code>public void on_deletePartner(Pointer p, Attributes a, Database db) {}</code><P>

Do not forget that you have to compile after changing a java file.<P>

<a href="makumba-spec.html#Business">More about business logic</a>


<script type="text/javascript">
   makeFooter("$Id$");
</script>

</body>
</html>
